.TH switchroot 8
'''
.SH NAME
switchroot \- replace initramfs with a newly mounted root filesystem.
'''
.SH SYNOPSIS
switchroot \fI/mnt/newroot\fR \fI/sbin/init\fR ...
'''
.SH DESCRIPTION
switchroot is a single-use tool needed to get rid of initramfs once the real
root has been mounted.
.P
Initramfs is a special filesystem loaded into the kernel early during boot,
serving as the root filesystem until the real root gets mounted. Typically
it contains just enough of userspace code to find and mount the real rootfs.
.P
Unlike any other mounted filesystem, initramfs cannot be unmounted, and
exchanging it with the real root using \fBpivot_root\fR(2) is not allowed. 
The real root must be mounted over initramfs, using move mount from its
original mountpoint to /.
.P
Before mounting the real root, initramfs must be wiped by unlinking all
the files there. Anything left behind will not be accessible but will still
waste kernel memory.
.P
When invoked, switchroot deletes everything on / without crossing file
system boundaries, move-mounts \fInewroot\fR to /, and executes
\fI/sbin/init\fR in the new root.
'''
.SH NOTES
switchroot does the equivalent of rm -r / before switching to the new root.
This is rather dangerous, so switchroot tries to make extra sure the files
being deleted reside on initramfs by calling \fBstatfs\fR(2).
.P
switchroot must always be run as pid 1, since it execs into \fBinit\fR(8).
This means the initramfs init must exec into switchroot.
.P
Any virtual filesystems that happen to be mounted onto initramfs will
be move-mounted onto the same location within newroot. Failing that,
switchroot will try to umount it.
'''
.SH SEE ALSO
\fBmount\fR(8), \fBmountvfs\fR(8), \fBmount\fR(2), \fBpivot_root\fR(2).
